import { Callout } from '@/components'

# TanStack Query v4, 5를 모두 지원

<Callout type='info'>

2.2.0 버전 이후로는 @tanstack/react-query v4와 v5을 모두 지원합니다. 더 낮은 버전의 브라우저를 지원하려면 @suspensive/react-query를 @tanstack/react-query v4와 함께 사용하세요.

</Callout>

<Callout type='warning'>

**TanStack Query v4에서 백포팅된 인터페이스 Deprecated 처리**

TanStack Query v4.40.0과 v4.41.0부터, 이전에 @suspensive/react-query에서 백포팅했던 여러 인터페이스들이 이제 TanStack Query에서 공식적으로 지원됩니다. 이러한 백포팅된 인터페이스들은 이제 deprecated 처리되었으며, 향후 버전에서 제거될 예정입니다.

**Deprecated된 인터페이스:**

- `queryOptions` (v4.40.0부터 사용 가능)
- `infiniteQueryOptions` (v4.41.0부터 사용 가능)
- `useSuspenseQuery`, `useSuspenseQueries`, `useSuspenseInfiniteQuery` (v4.40.0부터 사용 가능)
- `SuspenseQueriesOptions`, `SuspenseQueriesResults` (v4.40.0부터 사용 가능)
- `UseSuspenseQueryOptions`, `UseSuspenseQueryResult` (v4.40.0부터 사용 가능)

**마이그레이션 필요:** TanStack Query v4.40.0+ 또는 v4.41.0+를 사용하고 있다면, @suspensive/react-query의 백포팅된 인터페이스 대신 TanStack Query의 공식 인터페이스로 마이그레이션해주세요.

</Callout>

@suspensive/react-query는 내부적으로 @tanstack/react-query의 버전에 대응하여 인터페이스를 제공하는 @suspensive/react-query-4와 @suspensive/react-query-5로 구성되어 있습니다. 사용자 환경에 설치된 @tanstack/react-query 버전을 감지하여 자동으로 호환되는 인터페이스를 제공합니다.

## Command-Line Interface (CLI)

@suspensive/react-query의 Command-Line Interface (CLI)는 @tanstack/react-query와의 호환성 문제를 해결하기 위한 도구입니다. 명령어를 통해 사용자 환경에 설치된 @tanstack/react-query와의 호환성을 확인하고, @suspensive/react-query의 인터페이스를 호환되는 인터페이스로 전환할 수 있습니다.

하지만 실제로 CLI를 사용할 일은 드물며, @suspensive/react-query 설치 시 자동으로 사용자 환경에 설치된 @tanstack/react-query과 호환되는 인터페이스를 제공합니다.

## 시작하기

CLI는 @suspensive/react-query 패키지에 포함되어 있습니다. 추가적인 설치는 필요 없으며, 아래 명령어를 통해 바로 사용할 수 있습니다.

```bash
npx suspensive-react-query
```

또는 간단히 `srq`로도 사용할 수 있습니다.

```bash
npx srq
```

## 명령어

현재 CLI가 제공하는 명령어는 총 5개로, 각 명령어의 설명은 다음과 같습니다.

| 명령어  | 설명                                                                                                                                          |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| version | 현재 설치된 @suspensive/react-query의 버전을 표시합니다.                                                                                      |
| help    | 명령어의 사용 방법을 콘솔에서 확인할 수 있습니다.                                                                                             |
| status  | 현재 사용 중인 @tanstack/react-query 버전과의 호환성을 확인합니다.                                                                            |
| switch  | @tanstack/react-query의 버전과 호환되는 Suspensive 인터페이스를 사용하도록 @suspensive/react-query의 내보내기(exports)를 전환합니다.          |
| fix     | @tanstack/react-query의 버전과 호환되는 Suspensive 인터페이스를 사용하도록 @suspensive/react-query의 내보내기(exports)를 자동으로 전환합니다. |

### version

현재 설치된 @suspensive/react-query의 버전을 표시합니다. 이는 패키지의 버전으로 `package.json`에 명시된 버전을 표시하며, @tanstack/react-query와 호환되도록 내부적으로 구성하는 @suspensive/react-query-4 또는 @suspensive/react-query-5의 버전을 의미하지는 않습니다.

```bash
npx suspensive-react-query -v
```

또는

```bash
npx suspensive-react-query --version
```

### help

명령어의 사용 방법을 콘솔에서 확인할 수 있습니다. 예를 들어 `fix` 명령어에 대해 자세히 알고 싶다면, 다음과 같이 명령어를 사용하여 확인할 수 있습니다.

```bash
npx suspensive-react-query fix -h
```

또는

```bash
npx suspensive-react-query --help
```

### status

현재 사용자 환경에 설치된 @tanstack/react-query와 @suspensive/react-query의 호환성 상태를 확인할 수 있으며, 사용 가능한 인터페이스 항목에서 어떤 인터페이스가 현재 환경에서 사용 가능한지 확인할 수 있습니다.

```bash
npx suspensive-react-query status
```

예를 들어, @suspensive/react-query@2.12.1 버전과 @tanstack/react-query@5.51.21 버전을 사용 중인 경우, 다음과 같은 결과를 확인할 수 있습니다.

```
┌─────────────────────────────────────────┬──────────┬────────────────────────────────────┐
│ @suspensive/react-query@2.12.1          │ status   │ available interfaces               │
├──────────┬──────────────────────────────┼──────────┼────────────────────────────────────┤
│ exports  │ @suspensive/react-query-5    │ 🟢       │ SuspenseQuery SuspenseQueries      │
│ from     │ @2.12.1                      │          │ SuspenseInfiniteQuery              │
│          │                              │          │ QueryErrorBoundary Mutation        │
│          ├──────────────────────────────┼──────────┼────────────────────────────────────┤
│          │ @tanstack/react-query        │ 🟢       │ useSuspenseQuery                   │
│          │ @5.51.21                     │          │ useSuspenseQueries                 │
│          │                              │          │ useSuspenseInfiniteQuery           │
│          │                              │          │ queryOptions infiniteQueryOptions  │
└──────────┴──────────────────────────────┴──────────┴────────────────────────────────────┘
```

### switch

사용자 환경에 설치된 @tanstack/react-query의 version과 호환되는 Suspensive 인터페이스를 사용하도록 @suspensive/react-query의 내보내기(exports)를 전환합니다. 이 작업은 @suspensive/react-query의 엔트리 파일(dist/index.js)을 업데이트하여 수행됩니다.

```typescript
// dist/index.js of @suspensive/react-query

// "npx suspensive-react-query switch 4"를 사용할 때
// @suspensive/react-query의 dist/index.js
export * from '@suspensive/react-query-4' // @tanstack/react-query@4용 Suspensive 인터페이스
// "npx suspensive-react-query switch 5"를 사용할 때
// @suspensive/react-query의 dist/index.js
export * from '@suspensive/react-query-5' // @tanstack/react-query@5용 Suspensive 인터페이스
```

@tanstack/react-query v5를 사용하고 있는데 오류가 발생하면, 다음 명령어를 사용하여 엔트리 파일(dist/index.js)을 업데이트하여 호환되는 인터페이스로 전환할 수 있습니다.

```bash
npx suspensive-react-query switch 5
```

### fix

`fix` 명령어는 @suspensive/react-query와 @tanstack/react-query이 호환되지 않는 환경에서 손쉽게 버전을 맞추는 간편한 방법입니다. 사용자 환경의 @tanstack/react-query의 버전과 호환되는 Suspensive 인터페이스를 사용하도록 @suspensive/react-query의 내보내기(exports)를 자동으로 전환합니다.

```bash
npx suspensive-react-query fix
```

## 문제 해결

빌드 중 @suspensive/react-query에 대한 오류가 발생하면, 대부분 설치된 @tanstack/react-query와의 호환성 문제로 발생되는 것입니다.

다음과 같은 방법으로 `package.json`에 사용하고자 하는 버전을 지정할 수 있습니다. 빌드 시 자동으로 올바른 버전을 사용하게 하려면 다음과 같이 스크립트를 사용할 수 있습니다.

```json
{
  "scripts": {
    "build": "suspensive-react-query fix && next build"
  }
}
```

또는 @suspensive/react-query의 버전을 고정하려면 다음과 같이 설정할 수 있습니다.

```json
{
  "scripts": {
    "build": "suspensive-react-query switch 5 && next build"
  }
}
```
